Webhook 服务详细配置指南

Webhook 服务详细配置指南

---

一、Webhook 服务核心概念

Webhook 是 Kubernetes 扩展认证（Authentication）和授权（Authorization）的核心机制，允许将请求转发到外部服务进行决策。以下是两种主要用途：

1. 认证（Authentication）
   验证请求者的身份（如 Token、客户端证书）。
2. 授权（Authorization）
   检查请求者是否有权限执行操作（如访问某资源）。

---

二、Webhook 服务实现详解

1. 编写 Webhook 服务

以下是一个完整的 授权 Webhook 服务 示例（Python + Flask），支持详细日志和策略控制。

python

复制

# authz_webhook.py
from flask import Flask, request, jsonify
import logging

app = Flask(__name__)
logging.basicConfig(level=logging.INFO)

@app.route('/authz', methods=['POST'])
def authz():
    try:
        request_data = request.json
        app.logger.info(f"Received authorization request: {request_data}")

        # 提取关键字段
        user = request_data["spec"]["user"]
        verb = request_data["spec"]["resourceAttributes"]["verb"]
        resource = request_data["spec"]["resourceAttributes"]["resource"]

        # 自定义授权逻辑（示例：仅允许 admin 用户执行 delete 操作）
        if user == "admin" and verb == "delete":
            allowed = True
        else:
            allowed = verb.lower() in ["get", "list"]  # 允许普通用户 get/list

        response = {
            "apiVersion": "authorization.k8s.io/v1",
            "kind": "SubjectAccessReview",
            "status": {
                "allowed": allowed,
                "denied": not allowed,  # 明确拒绝（可选）
                "reason": "Allowed by custom policy" if allowed else "Forbidden: Insufficient permissions"
            }
        }
        return jsonify(response)
    except Exception as e:
        app.logger.error(f"Error processing request: {e}")
        return jsonify({"status": {"allowed": False, "reason": "Internal server error"}}), 500

if __name__ == '__main__':
    # 生产环境需使用 HTTPS 和正式证书
    app.run(host='0.0.0.0', port=8443, ssl_context=('webhook.crt', 'webhook.key'))

---

2. 生成 TLS 证书（生产环境推荐）

Webhook 必须使用 HTTPS，建议使用集群 CA 签发证书以提高安全性。

bash

复制

# 生成证书签名请求（CSR）
openssl req -new -newkey rsa:2048 -nodes -keyout webhook.key -out webhook.csr -subj "/CN=authz-webhook.default.svc"

# 使用集群 CA 签发证书（假设 CA 位于 /etc/kubernetes/pki）
sudo openssl x509 -req -days 365 -in webhook.csr -CA /etc/kubernetes/pki/ca.crt -CAkey /etc/kubernetes/pki/ca.key -CAcreateserial -out webhook.crt

# 验证证书
openssl x509 -in webhook.crt -noout -text

---

3. 部署 Webhook 服务到 Kubernetes

将 Webhook 服务部署为 Kubernetes Deployment 和 Service，确保高可用性。

yaml

复制

# webhook-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: authz-webhook
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: authz-webhook
  template:
    metadata:
      labels:
        app: authz-webhook
    spec:
      containers:
      - name: webhook
        image: python:3.9-slim
        command: ["python", "authz_webhook.py"]
        ports:
        - containerPort: 8443
        volumeMounts:
        - name: certs
          mountPath: "/certs"
          readOnly: true
        - name: code
          mountPath: "/app"
      volumes:
      - name: certs
        secret:
          secretName: webhook-certs
      - name: code
        configMap:
          name: webhook-code

---
# webhook-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: authz-webhook
  namespace: default
spec:
  selector:
    app: authz-webhook
  ports:
  - protocol: TCP
    port: 8443
    targetPort: 8443

---
# webhook-configmap.yaml (将代码和配置注入容器)
apiVersion: v1
kind: ConfigMap
metadata:
  name: webhook-code
  namespace: default
data:
  authz_webhook.py: |
    # 此处粘贴完整的 Python 代码

---
# webhook-secret.yaml (存储证书)
apiVersion: v1
kind: Secret
metadata:
  name: webhook-certs
  namespace: default
type: kubernetes.io/tls
data:
  tls.crt: $(base64 -w0 webhook.crt | tr -d '\n')
  tls.key: $(base64 -w0 webhook.key | tr -d '\n')

应用配置：

bash

复制

kubectl apply -f webhook-deployment.yaml
kubectl apply -f webhook-service.yaml
kubectl apply -f webhook-configmap.yaml
kubectl apply -f webhook-secret.yaml

---

4. 配置 Kubernetes API 服务器

修改 kube-apiserver 配置以启用 Webhook 授权。

bash

复制

sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml

添加以下参数和卷挂载：

yaml

复制

spec:
  containers:
  - command:
    - kube-apiserver
    # 启用 Webhook 授权模式
    - --authorization-mode=Node,RBAC,Webhook
    - --authorization-webhook-config-file=/etc/kubernetes/webhook/authz-config.yaml
    # 控制 Webhook 失败时的行为（true=允许，false=拒绝）
    - --authorization-webhook-fail-open=false
    # 其他原有参数...
    volumeMounts:
    - name: webhook-config
      mountPath: /etc/kubernetes/webhook/
    - name: cluster-ca
      mountPath: /etc/kubernetes/pki/
  volumes:
  - name: webhook-config
    hostPath:
      path: /etc/kubernetes/webhook/
      type: DirectoryOrCreate
  - name: cluster-ca
    hostPath:
      path: /etc/kubernetes/pki/
      type: DirectoryOrCreate

创建 Webhook 配置文件 /etc/kubernetes/webhook/authz-config.yaml：

yaml

复制

apiVersion: v1
kind: Config
clusters:
- name: authz-webhook
  cluster:
    server: "https://authz-webhook.default.svc:8443/authz"  # 使用 Service DNS
    certificate-authority: "/etc/kubernetes/pki/ca.crt"    # 集群 CA 证书
users:
- name: kube-apiserver
current-context: webhook
contexts:
- context:
    cluster: authz-webhook
    user: kube-apiserver
  name: webhook

---

5. 重启 API 服务器并验证

保存配置文件后，kubelet 会自动重启 API 服务器。检查日志确认配置已生效：

bash

复制

# 查看 API 服务器日志
kubectl logs -n kube-system kube-apiserver-<master-node-name> | grep -i webhook

# 检查授权模式
kubectl describe pod kube-apiserver-<master-node-name> -n kube-system | grep "authorization-mode"

---

6. 测试 Webhook 策略

场景 1：普通用户尝试删除 Pod

bash

复制

kubectl delete pod my-pod --as=user1

预期结果：
Error from server (Forbidden): pods "my-pod" is forbidden: User "user1" cannot delete resource "pods" in API group "" in the namespace "default"

场景 2：Admin 用户删除 Pod

bash

复制

kubectl delete pod my-pod --as=admin

预期结果：删除成功（需在 Webhook 代码中实现 admin 权限逻辑）。

---

7. 生产环境最佳实践

1. 高可用性

   • 部署 Webhook 服务的多个副本，并通过 Service 负载均衡。

   • 设置 readinessProbe 和 livenessProbe：
     yaml

     复制

     livenessProbe:
       httpGet:
         path: /healthz
         port: 8443
         scheme: HTTPS
     readinessProbe:
       httpGet:
         path: /readyz
         port: 8443
         scheme: HTTPS
     

2. 监控与日志
   • 集成 Prometheus 监控 Webhook 服务的响应时间和错误率。
   • 记录详细的审计日志（如记录用户、操作和资源）。
3. 性能优化

   • 调整缓存时间以减少重复请求：
     yaml

     复制

     - --authorization-webhook-cache-authorized-ttl=10m
     - --authorization-webhook-cache-unauthorized-ttl=1m
     

4. 安全加固
   • 使用 RBAC 限制 Webhook 服务的权限。
   • 定期轮换证书（通过 Cert-Manager 自动化管理）。

---

8. 故障排查

错误 1：证书验证失败（x509: certificate signed by unknown authority）

• 解决：确保 API 服务器信任 Webhook 证书的 CA。若使用集群 CA，挂载 /etc/kubernetes/pki/ca.crt。

错误 2：Webhook 服务不可达（Failed calling webhook）

• 检查项：
  • Service 的 Endpoints 是否正常：kubectl get endpoints authz-webhook
  • 网络策略是否允许 API 服务器访问 Webhook Service。
  • Webhook 服务的 Pod 日志：kubectl logs -l app=authz-webhook

错误 3：授权响应格式错误

• 解决：确保 Webhook 返回的 JSON 符合 Kubernetes 的 SubjectAccessReview 结构。

---

总结

通过上述步骤，您可以将一个自定义的 Webhook 服务深度集成到 Kubernetes 的授权流程中。关键在于：

1. 正确生成和配置 TLS 证书。
2. 编写符合 Kubernetes API 规范的 Webhook 服务。
3. 精细控制 kube-apiserver 的启动参数和配置文件。
4. 全面的测试和监控。

此方案不仅适用于授权，稍作调整即可用于认证（Authentication Webhook），为企业提供统一的身份与权限管理入口。